@promptbook/cli 0.114.0-13 → 0.114.0-18

package/apps/agents-server/src/utils/agentProjects/agentProjectRuntimeAutostartScheduler.ts

@@ -0,0 +1,162 @@
+import { resolveAgentProjectRuntimeEnvironmentFlag } from './resolveAgentProjectRuntimeEnvironmentFlag';
+import { startDefaultAgentProjectRuntimes } from './startDefaultAgentProjectRuntimes';
+
+/**
+ * Environment variable that can force-enable or force-disable starting projects automatically.
+ */
+export const PTBK_AGENT_PROJECT_RUNTIME_AUTOSTART_ENABLED_ENV = 'PTBK_AGENT_PROJECT_RUNTIME_AUTOSTART_ENABLED';
+
+/**
+ * Global key used to keep one automatic project-start scheduler per Node.js process.
+ */
+const AGENT_PROJECT_RUNTIME_AUTOSTART_SCHEDULER_GLOBAL_KEY = '__PROMPTBOOK_AGENT_PROJECT_RUNTIME_AUTOSTART__';
+
+/**
+ * How often the server checks whether every project is in the state it is expected to be in.
+ *
+ * Five minutes is short enough for a freshly created project and for a crashed one to come back
+ * without anybody pressing a button, and long enough that a project which cannot start is retried
+ * rarely instead of constantly.
+ */
+export const AGENT_PROJECT_RUNTIME_AUTOSTART_INTERVAL_MS = 5 * 60 * 1000;
+
+/**
+ * Scheduler state stored on `globalThis` to survive module reloads.
+ */
+type AgentProjectRuntimeAutostartSchedulerState = {
+    /**
+     * Whether the scheduler has been bootstrapped in this process.
+     */
+    isBootstrapped: boolean;
+
+    /**
+     * Whether one pass is currently running.
+     */
+    isRunning: boolean;
+
+    /**
+     * Pending timer, if any.
+     */
+    timeout: NodeJS.Timeout | null;
+};
+
+/**
+ * Global object shape used for process-wide scheduler state.
+ */
+type AgentProjectRuntimeAutostartSchedulerGlobal = typeof globalThis & {
+    [AGENT_PROJECT_RUNTIME_AUTOSTART_SCHEDULER_GLOBAL_KEY]?: AgentProjectRuntimeAutostartSchedulerState;
+};
+
+/**
+ * Starts all projects which are expected to be running and keeps them that way.
+ *
+ * The first pass runs immediately but never blocks the caller, so a restarted server serves its
+ * first request while the projects behind it are coming up.
+ */
+export function ensureAgentProjectRuntimeAutostartBootstrapped(): void {
+    if (!isAgentProjectRuntimeAutostartAvailable()) {
+        return;
+    }
+
+    const state = getAgentProjectRuntimeAutostartSchedulerState();
+    if (state.isBootstrapped) {
+        return;
+    }
+
+    state.isBootstrapped = true;
+    void runAgentProjectRuntimeAutostartPass();
+}
+
+/**
+ * Schedules the next pass.
+ */
+function scheduleNextAgentProjectRuntimeAutostartPass(): void {
+    const state = getAgentProjectRuntimeAutostartSchedulerState();
+    clearAgentProjectRuntimeAutostartTimer(state);
+
+    state.timeout = setTimeout(() => {
+        void runAgentProjectRuntimeAutostartPass();
+    }, AGENT_PROJECT_RUNTIME_AUTOSTART_INTERVAL_MS);
+    state.timeout.unref?.();
+}
+
+/**
+ * Runs one pass and reschedules the next one.
+ *
+ * Every failure only logs and never throws: a project which cannot be started must never take down
+ * the scheduler or the running server.
+ */
+async function runAgentProjectRuntimeAutostartPass(): Promise<void> {
+    const state = getAgentProjectRuntimeAutostartSchedulerState();
+    if (state.isRunning) {
+        scheduleNextAgentProjectRuntimeAutostartPass();
+        return;
+    }
+
+    state.isRunning = true;
+
+    try {
+        const report = await startDefaultAgentProjectRuntimes();
+
+        if (report.startedProjectCount > 0 || report.failedProjectCount > 0) {
+            console.info(
+                `🚀 Started ${report.startedProjectCount} agent project(s), ${report.runningProjectCount} already running, ${report.stoppedProjectCount} left stopped, ${report.failedProjectCount} failed.`,
+            );
+        }
+    } catch (error) {
+        console.error('[agent-project-runtimes] automatic project start failed', error);
+    } finally {
+        state.isRunning = false;
+        scheduleNextAgentProjectRuntimeAutostartPass();
+    }
+}
+
+/**
+ * Clears one pending scheduler timer.
+ *
+ * @param state - Process-wide scheduler state.
+ */
+function clearAgentProjectRuntimeAutostartTimer(state: AgentProjectRuntimeAutostartSchedulerState): void {
+    if (!state.timeout) {
+        return;
+    }
+
+    clearTimeout(state.timeout);
+    state.timeout = null;
+}
+
+/**
+ * Returns process-wide scheduler state.
+ *
+ * @returns Mutable scheduler state.
+ */
+function getAgentProjectRuntimeAutostartSchedulerState(): AgentProjectRuntimeAutostartSchedulerState {
+    const schedulerGlobal = globalThis as AgentProjectRuntimeAutostartSchedulerGlobal;
+    schedulerGlobal[AGENT_PROJECT_RUNTIME_AUTOSTART_SCHEDULER_GLOBAL_KEY] ??= {
+        isBootstrapped: false,
+        isRunning: false,
+        timeout: null,
+    };
+
+    return schedulerGlobal[AGENT_PROJECT_RUNTIME_AUTOSTART_SCHEDULER_GLOBAL_KEY]!;
+}
+
+/**
+ * Returns whether the current process should start projects automatically.
+ *
+ * Projects are server-owned processes, so they are only started from a real Node.js server process,
+ * never during tests or the Next.js production build.
+ *
+ * @returns `true` when this process may own project runtimes.
+ */
+function isAgentProjectRuntimeAutostartAvailable(): boolean {
+    if (process.env.NODE_ENV === 'test' || process.env.JEST_WORKER_ID !== undefined) {
+        return false;
+    }
+
+    if (process.env.NEXT_PHASE === 'phase-production-build') {
+        return false;
+    }
+
+    return resolveAgentProjectRuntimeEnvironmentFlag(PTBK_AGENT_PROJECT_RUNTIME_AUTOSTART_ENABLED_ENV) ?? true;
+}

package/apps/agents-server/src/utils/agentProjects/agentProjectRuntimeDesiredState.ts

@@ -0,0 +1,252 @@
+import { mkdir, readFile, writeFile } from 'fs/promises';
+import { dirname } from 'path';
+import { UnexpectedError } from '../../../../../src/errors/UnexpectedError';
+import { spaceTrim } from '../../../../../src/utils/organization/spaceTrim';
+import { isSameAgentProjectIdentity, type AgentProjectIdentity } from './agentProjectIdentity';
+import { resolveAgentProjectRuntimeDesiredStateFilePath } from './agentProjectRuntimePaths';
+import { runAgentProjectStateMutation } from './agentProjectStateMutationQueue';
+
+/**
+ * States one agent project can be asked to be in.
+ */
+export const AGENT_PROJECT_RUNTIME_DESIRED_STATES = ['running', 'stopped'] as const;
+
+/**
+ * State one agent project is expected to be in until somebody decides otherwise.
+ */
+export type AgentProjectRuntimeDesiredState = (typeof AGENT_PROJECT_RUNTIME_DESIRED_STATES)[number];
+
+/**
+ * State of every project which was never explicitly stopped.
+ *
+ * A project exists to be reachable, so being started is its default — only an explicit stop
+ * keeps it down across server restarts.
+ */
+export const DEFAULT_AGENT_PROJECT_RUNTIME_DESIRED_STATE: AgentProjectRuntimeDesiredState = 'running';
+
+/**
+ * Global key used to serialize desired-state mutations across concurrent requests.
+ */
+const AGENT_PROJECT_RUNTIME_DESIRED_STATE_GLOBAL_KEY = '__PROMPTBOOK_AGENT_PROJECT_RUNTIME_DESIRED_STATE__';
+
+/**
+ * Current persisted desired-state schema version.
+ */
+const AGENT_PROJECT_RUNTIME_DESIRED_STATE_VERSION = 1;
+
+/**
+ * Persisted decision to run or not to run one agent project.
+ */
+export type AgentProjectRuntimeDesiredStateRecord = AgentProjectIdentity & {
+    /**
+     * State the project should be in.
+     */
+    readonly desiredState: AgentProjectRuntimeDesiredState;
+
+    /**
+     * ISO timestamp when this decision was made.
+     */
+    readonly updatedAt: string;
+};
+
+/**
+ * Persisted desired-state document shape.
+ */
+type PersistedAgentProjectRuntimeDesiredStates = {
+    readonly version: number;
+    readonly projects: ReadonlyArray<AgentProjectRuntimeDesiredStateRecord>;
+};
+
+/**
+ * Lists every explicit decision to run or not to run a project.
+ *
+ * Projects nobody ever started or stopped are absent from the list — they run by default.
+ *
+ * @returns Persisted desired-state records.
+ */
+export async function listAgentProjectRuntimeDesiredStates(): Promise<
+    ReadonlyArray<AgentProjectRuntimeDesiredStateRecord>
+> {
+    const desiredStateFilePath = resolveAgentProjectRuntimeDesiredStateFilePath();
+    let rawContent: string;
+
+    try {
+        rawContent = await readFile(desiredStateFilePath, 'utf-8');
+    } catch (error) {
+        if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+            return [];
+        }
+
+        throw new UnexpectedError(
+            spaceTrim(`
+                Failed to read agent project desired states.
+
+                **Desired state file:** \`${desiredStateFilePath}\`
+                **Cause:** \`${error instanceof Error ? error.message : String(error)}\`
+            `),
+        );
+    }
+
+    try {
+        return parsePersistedAgentProjectRuntimeDesiredStates(JSON.parse(rawContent));
+    } catch (error) {
+        throw new UnexpectedError(
+            spaceTrim(`
+                Failed to parse agent project desired states.
+
+                **Desired state file:** \`${desiredStateFilePath}\`
+                **Cause:** \`${error instanceof Error ? error.message : String(error)}\`
+            `),
+        );
+    }
+}
+
+/**
+ * Resolves the desired state of one project from already-loaded records.
+ *
+ * This is the one place deciding what "no record at all" means, so a caller which reads every
+ * record once — such as the automatic project start — answers the same question the same way.
+ *
+ * @param desiredStateRecords - Persisted desired-state records.
+ * @param identity - Agent and project identification.
+ * @returns State the project should be in.
+ */
+export function resolveAgentProjectRuntimeDesiredStateFromRecords(
+    desiredStateRecords: ReadonlyArray<AgentProjectRuntimeDesiredStateRecord>,
+    identity: AgentProjectIdentity,
+): AgentProjectRuntimeDesiredState {
+    const desiredStateRecord = desiredStateRecords.find((record) => isSameAgentProjectIdentity(record, identity));
+
+    return desiredStateRecord?.desiredState ?? DEFAULT_AGENT_PROJECT_RUNTIME_DESIRED_STATE;
+}
+
+/**
+ * Resolves the desired state of one single project.
+ *
+ * @param identity - Agent and project identification.
+ * @returns State the project should be in.
+ */
+export async function resolveAgentProjectRuntimeDesiredState(
+    identity: AgentProjectIdentity,
+): Promise<AgentProjectRuntimeDesiredState> {
+    return resolveAgentProjectRuntimeDesiredStateFromRecords(await listAgentProjectRuntimeDesiredStates(), identity);
+}
+
+/**
+ * Remembers that one project should be running or should stay stopped.
+ *
+ * Nothing is written when the project is already expected to be in the requested state, so a
+ * project which simply runs by default never grows a record of its own.
+ *
+ * @param options - Agent and project identification together with the requested state.
+ */
+export async function setAgentProjectRuntimeDesiredState(
+    options: AgentProjectIdentity & {
+        /**
+         * State the project should be in from now on.
+         */
+        readonly desiredState: AgentProjectRuntimeDesiredState;
+    },
+): Promise<void> {
+    await runAgentProjectStateMutation(AGENT_PROJECT_RUNTIME_DESIRED_STATE_GLOBAL_KEY, async () => {
+        const desiredStateRecords = await listAgentProjectRuntimeDesiredStates();
+
+        if (resolveAgentProjectRuntimeDesiredStateFromRecords(desiredStateRecords, options) === options.desiredState) {
+            return;
+        }
+
+        const changedRecord: AgentProjectRuntimeDesiredStateRecord = {
+            agentPermanentId: options.agentPermanentId,
+            projectName: options.projectName,
+            desiredState: options.desiredState,
+            updatedAt: new Date().toISOString(),
+        };
+
+        await writeAgentProjectRuntimeDesiredStates([
+            ...desiredStateRecords.filter((record) => !isSameAgentProjectIdentity(record, options)),
+            changedRecord,
+        ]);
+    });
+}
+
+/**
+ * Persists all desired-state records.
+ *
+ * @param desiredStateRecords - Records to persist.
+ */
+async function writeAgentProjectRuntimeDesiredStates(
+    desiredStateRecords: ReadonlyArray<AgentProjectRuntimeDesiredStateRecord>,
+): Promise<void> {
+    const desiredStateFilePath = resolveAgentProjectRuntimeDesiredStateFilePath();
+    const payload: PersistedAgentProjectRuntimeDesiredStates = {
+        version: AGENT_PROJECT_RUNTIME_DESIRED_STATE_VERSION,
+        projects: [...desiredStateRecords].sort((firstRecord, secondRecord) =>
+            `${firstRecord.agentPermanentId}/${firstRecord.projectName}`.localeCompare(
+                `${secondRecord.agentPermanentId}/${secondRecord.projectName}`,
+            ),
+        ),
+    };
+
+    try {
+        await mkdir(dirname(desiredStateFilePath), { recursive: true });
+        await writeFile(desiredStateFilePath, `${JSON.stringify(payload, null, 4)}\n`, 'utf-8');
+    } catch (error) {
+        throw new UnexpectedError(
+            spaceTrim(`
+                Failed to persist agent project desired states.
+
+                **Desired state file:** \`${desiredStateFilePath}\`
+                **Cause:** \`${error instanceof Error ? error.message : String(error)}\`
+            `),
+        );
+    }
+}
+
+/**
+ * Parses persisted desired-state records and ignores invalid rows.
+ */
+function parsePersistedAgentProjectRuntimeDesiredStates(
+    rawValue: unknown,
+): ReadonlyArray<AgentProjectRuntimeDesiredStateRecord> {
+    if (!rawValue || typeof rawValue !== 'object') {
+        return [];
+    }
+
+    const desiredStates = rawValue as Partial<PersistedAgentProjectRuntimeDesiredStates>;
+
+    if (!Array.isArray(desiredStates.projects)) {
+        return [];
+    }
+
+    return desiredStates.projects
+        .map((rawRecord): AgentProjectRuntimeDesiredStateRecord | null => {
+            if (!rawRecord || typeof rawRecord !== 'object') {
+                return null;
+            }
+
+            const record = rawRecord as Partial<AgentProjectRuntimeDesiredStateRecord>;
+
+            if (
+                typeof record.agentPermanentId !== 'string' ||
+                typeof record.projectName !== 'string' ||
+                !isAgentProjectRuntimeDesiredState(record.desiredState)
+            ) {
+                return null;
+            }
+
+            return {
+                agentPermanentId: record.agentPermanentId,
+                projectName: record.projectName,
+                desiredState: record.desiredState,
+                updatedAt: typeof record.updatedAt === 'string' ? record.updatedAt : new Date(0).toISOString(),
+            };
+        })
+        .filter((record): record is AgentProjectRuntimeDesiredStateRecord => record !== null);
+}
+
+/**
+ * Checks whether a raw value is a known desired state.
+ */
+function isAgentProjectRuntimeDesiredState(value: unknown): value is AgentProjectRuntimeDesiredState {
+    return AGENT_PROJECT_RUNTIME_DESIRED_STATES.includes(value as AgentProjectRuntimeDesiredState);
+}

package/apps/agents-server/src/utils/agentProjects/agentProjectRuntimeDisplay.ts

@@ -21,10 +21,14 @@ export function formatAgentProjectRuntimeMode(mode: AgentProjectRuntimeMode): st
 /**
  * Formats one project runtime status for UI display.
  *
- * @param runtime - Runtime info.
+ * @param runtime - Runtime info, or `null` for a project which has no runtime at all.
  * @returns Human-readable status label.
  */
-export function formatAgentProjectRuntimeStatus(runtime: AgentProjectRuntimeInfo): string {
+export function formatAgentProjectRuntimeStatus(runtime: AgentProjectRuntimeInfo | null): string {
+    if (!runtime) {
+        return 'Not running';
+    }
+
     if (runtime.isRunning) {
         return 'Running';
     }
@@ -39,4 +43,3 @@ export function formatAgentProjectRuntimeStatus(runtime: AgentProjectRuntimeInfo
 
     return 'Stopped';
 }
-

package/apps/agents-server/src/utils/agentProjects/agentProjectRuntimeDomains.ts

@@ -9,6 +9,7 @@ import {
     resolveAgentProjectDomainRegistryFilePath,
     resolveAgentProjectDomainsFilePath,
 } from './agentProjectRuntimePaths';
+import { runAgentProjectStateMutation } from './agentProjectStateMutationQueue';
 
 /**
  * Current on-disk domain registry schema version.
@@ -139,23 +140,6 @@ type PersistedAgentProjectDomainRegistry = {
     readonly domains: ReadonlyArray<AgentProjectDomainRecord>;
 };
 
-/**
- * Process-wide domain registry state.
- */
-type AgentProjectDomainRegistryState = {
-    /**
-     * Promise chain used as a lightweight mutation queue.
-     */
-    domainMutationQueue: Promise<void>;
-};
-
-/**
- * Global object shape used for process-wide domain registry state.
- */
-type AgentProjectDomainRegistryGlobal = typeof globalThis & {
-    [AGENT_PROJECT_DOMAIN_REGISTRY_GLOBAL_KEY]?: AgentProjectDomainRegistryState;
-};
-
 /**
  * Assigns or refreshes the stable public domain for one agent project.
  *
@@ -483,21 +467,7 @@ async function writeAgentProjectDomainRecords(records: ReadonlyArray<AgentProjec
  * Runs one domain-registry mutation after previous mutations have finished.
  */
 async function runAgentProjectDomainRegistryMutation<TValue>(operation: () => Promise<TValue>): Promise<TValue> {
-    const registryState = getAgentProjectDomainRegistryState();
-    const previousMutation = registryState.domainMutationQueue;
-    let releaseMutation!: () => void;
-
-    registryState.domainMutationQueue = new Promise<void>((resolve) => {
-        releaseMutation = resolve;
-    });
-
-    await previousMutation.catch(() => undefined);
-
-    try {
-        return await operation();
-    } finally {
-        releaseMutation();
-    }
+    return await runAgentProjectStateMutation(AGENT_PROJECT_DOMAIN_REGISTRY_GLOBAL_KEY, operation);
 }
 
 /**
@@ -719,15 +689,3 @@ async function writeTextFile(filePath: string, content: string): Promise<void> {
     await mkdir(dirname(filePath), { recursive: true });
     await writeFile(filePath, content, 'utf-8');
 }
-
-/**
- * Returns process-wide project-domain registry state.
- */
-function getAgentProjectDomainRegistryState(): AgentProjectDomainRegistryState {
-    const registryGlobal = globalThis as AgentProjectDomainRegistryGlobal;
-    registryGlobal[AGENT_PROJECT_DOMAIN_REGISTRY_GLOBAL_KEY] ??= {
-        domainMutationQueue: Promise.resolve(),
-    };
-
-    return registryGlobal[AGENT_PROJECT_DOMAIN_REGISTRY_GLOBAL_KEY]!;
-}

package/apps/agents-server/src/utils/agentProjects/agentProjectRuntimePaths.ts

@@ -15,6 +15,11 @@ export const PTBK_AGENT_PROJECT_DOMAIN_REGISTRY_FILE_ENV = 'PTBK_AGENT_PROJECT_D
  */
 export const PTBK_AGENT_PROJECT_DOMAINS_FILE_ENV = 'PTBK_AGENT_PROJECT_DOMAINS_FILE';
 
+/**
+ * Environment variable overriding the persisted project desired-state file.
+ */
+export const PTBK_AGENT_PROJECT_RUNTIME_DESIRED_STATE_FILE_ENV = 'PTBK_AGENT_PROJECT_RUNTIME_DESIRED_STATE_FILE';
+
 /**
  * Directory under the Agents Server data root used for project runtime state.
  */
@@ -35,6 +40,11 @@ const AGENT_PROJECT_DOMAIN_REGISTRY_FILE_NAME = 'domains.json';
  */
 const AGENT_PROJECT_DOMAINS_FILE_NAME = 'domains.txt';
 
+/**
+ * Persisted desired-state filename.
+ */
+const AGENT_PROJECT_RUNTIME_DESIRED_STATE_FILE_NAME = 'desired-states.json';
+
 /**
  * Resolves the durable state root used by agent project runtime managers.
  *
@@ -86,6 +96,21 @@ export function resolveAgentProjectDomainRegistryFilePath(): string {
     return join(resolveAgentProjectRuntimeStateRoot(), AGENT_PROJECT_DOMAIN_REGISTRY_FILE_NAME);
 }
 
+/**
+ * Resolves the JSON file remembering which projects were explicitly started or stopped.
+ *
+ * @returns Absolute file path.
+ */
+export function resolveAgentProjectRuntimeDesiredStateFilePath(): string {
+    const configuredFilePath = process.env[PTBK_AGENT_PROJECT_RUNTIME_DESIRED_STATE_FILE_ENV]?.trim();
+
+    if (configuredFilePath) {
+        return resolve(configuredFilePath);
+    }
+
+    return join(resolveAgentProjectRuntimeStateRoot(), AGENT_PROJECT_RUNTIME_DESIRED_STATE_FILE_NAME);
+}
+
 /**
  * Resolves the newline-separated domain file consumed by the VPS installer.
  *

package/apps/agents-server/src/utils/agentProjects/agentProjectRuntimePm2.ts

@@ -3,6 +3,7 @@ import { createHash } from 'crypto';
 import { promisify } from 'util';
 import { AGENT_PROJECT_RUNTIME_HOST } from './agentProjectRuntimeConstants';
 import type { AgentProjectRuntimeMode } from './AgentProjectRuntimeInfo';
+import { resolveAgentProjectRuntimeEnvironmentFlag } from './resolveAgentProjectRuntimeEnvironmentFlag';
 
 const execFileAsync = promisify(execFile);
 
@@ -137,10 +138,10 @@ export type StartAgentProjectRuntimePm2ProcessOptions = {
  * @returns `true` on production Linux unless explicitly disabled.
  */
 export function isAgentProjectRuntimePm2Enabled(): boolean {
-    const configuredValue = process.env[PTBK_AGENT_PROJECT_RUNTIME_PM2_ENABLED_ENV]?.trim().toLowerCase();
+    const configuredFlag = resolveAgentProjectRuntimeEnvironmentFlag(PTBK_AGENT_PROJECT_RUNTIME_PM2_ENABLED_ENV);
 
-    if (configuredValue) {
-        return ['1', 'true', 'yes', 'y'].includes(configuredValue);
+    if (configuredFlag !== null) {
+        return configuredFlag;
     }
 
     return process.platform === 'linux' && process.env.NODE_ENV === 'production';