@promptbook/cli 0.114.0-13 → 0.114.0-18

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

@@ -13,6 +13,7 @@ import type {
     AgentProjectRuntimeMode,
     AgentProjectRuntimeStatus,
 } from './AgentProjectRuntimeInfo';
+import { isSameAgentProjectIdentity } from './agentProjectIdentity';
 import {
     AGENT_PROJECT_RUNTIME_DEFAULT_DEV_COMMAND,
     AGENT_PROJECT_RUNTIME_HOST,
@@ -21,6 +22,7 @@ import {
     AGENT_PROJECT_RUNTIME_STOP_POLL_INTERVAL_MS,
     AGENT_PROJECT_RUNTIME_STOP_TIMEOUT_MS,
 } from './agentProjectRuntimeConstants';
+import { setAgentProjectRuntimeDesiredState } from './agentProjectRuntimeDesiredState';
 import {
     assignAgentProjectDomain,
     resolveAgentProjectDomainRecord,
@@ -207,6 +209,9 @@ export async function assignAgentProjectPort(
 /**
  * Starts one project using its npm `dev` script when available, otherwise a static file server.
  *
+ * Starting a project also makes it expected to be running, so a project which was stopped earlier
+ * is started again by itself after the next server restart.
+ *
  * @param options - Agent and project identification.
  * @returns Runtime info for the started project.
  */
@@ -216,6 +221,15 @@ export async function startAgentProjectRuntime(
     await hydrateAgentProjectRuntimeRegistryState();
 
     const project = await resolveExistingAgentProject(options);
+
+    // Note: The intent is remembered before the project is started so that a project which fails to
+    //       start now is still tried again by the next automatic pass.
+    await setAgentProjectRuntimeDesiredState({
+        agentPermanentId: options.agentPermanentId,
+        projectName: project.projectName,
+        desiredState: 'running',
+    });
+
     const isDevRuntime = await hasAgentProjectDevScript(project.absolutePath);
     const preparedStart = await prepareAgentProjectRuntimeStart(options, project);
 
@@ -375,7 +389,9 @@ export async function listAgentProjectRuntimes(): Promise<ReadonlyArray<AgentPro
 }
 
 /**
- * Terminates one runtime by runtime id.
+ * Terminates one runtime by runtime id on explicit request.
+ *
+ * The project is remembered as stopped, so it stays down until it is started again.
  *
  * @param runtimeId - Runtime id.
  * @returns Terminated runtime info or `null` when it no longer exists.
@@ -389,14 +405,19 @@ export async function terminateAgentProjectRuntimeById(runtimeId: string): Promi
         return null;
     }
 
-    await terminateAgentProjectRuntimeRecord(runtimeRecord);
-    getAgentProjectRuntimeRegistryState().runtimesById.delete(runtimeId);
-    await persistAgentProjectRuntimeRegistryState();
-    return toAgentProjectRuntimeInfo(runtimeRecord);
+    await setAgentProjectRuntimeDesiredState({
+        agentPermanentId: runtimeRecord.agentPermanentId,
+        projectName: runtimeRecord.projectName,
+        desiredState: 'stopped',
+    });
+
+    return await removeAgentProjectRuntimeById(runtimeId);
 }
 
 /**
- * Terminates any runtime assigned to one project.
+ * Terminates any runtime assigned to one project on explicit request.
+ *
+ * The project is remembered as stopped, so it stays down until it is started again.
  *
  * @param options - Agent and project identification.
  * @returns Terminated runtime info or `null` when no runtime exists.
@@ -405,30 +426,64 @@ export async function terminateAgentProjectRuntimeForProject(
     options: AgentProjectRuntimeProjectOptions,
 ): Promise<AgentProjectRuntimeInfo | null> {
     await hydrateAgentProjectRuntimeRegistryState();
+    await setAgentProjectRuntimeDesiredState({
+        agentPermanentId: options.agentPermanentId,
+        projectName: options.projectName,
+        desiredState: 'stopped',
+    });
 
-    const runtimeRecord = findAgentProjectRuntimeRecord(options.agentPermanentId, options.projectName);
+    return await removeAgentProjectRuntimeForProject(options);
+}
+
+/**
+ * Terminates all project runtimes in the current process.
+ *
+ * This is used by tests and process-level cleanup, so it says nothing about which projects should
+ * be running — every project keeps the state it is expected to be in.
+ */
+export async function terminateAllAgentProjectRuntimes(): Promise<void> {
+    await hydrateAgentProjectRuntimeRegistryState();
+
+    const runtimeIds = [...getAgentProjectRuntimeRegistryState().runtimesById.keys()];
+
+    await Promise.all(runtimeIds.map((runtimeId) => removeAgentProjectRuntimeById(runtimeId)));
+}
+
+/**
+ * Terminates one runtime by runtime id without changing which state the project is expected to be in.
+ *
+ * @param runtimeId - Runtime id.
+ * @returns Terminated runtime info or `null` when it no longer exists.
+ */
+async function removeAgentProjectRuntimeById(runtimeId: string): Promise<AgentProjectRuntimeInfo | null> {
+    const runtimeRecord = getAgentProjectRuntimeRegistryState().runtimesById.get(runtimeId);
 
     if (!runtimeRecord) {
         return null;
     }
 
     await terminateAgentProjectRuntimeRecord(runtimeRecord);
-    getAgentProjectRuntimeRegistryState().runtimesById.delete(runtimeRecord.id);
+    getAgentProjectRuntimeRegistryState().runtimesById.delete(runtimeId);
     await persistAgentProjectRuntimeRegistryState();
     return toAgentProjectRuntimeInfo(runtimeRecord);
 }
 
 /**
- * Terminates all project runtimes in the current process.
+ * Terminates the runtime of one project without changing which state the project is expected to be in.
  *
- * This is used by tests and process-level cleanup.
+ * @param options - Agent and project identification.
+ * @returns Terminated runtime info or `null` when no runtime exists.
  */
-export async function terminateAllAgentProjectRuntimes(): Promise<void> {
-    await hydrateAgentProjectRuntimeRegistryState();
+async function removeAgentProjectRuntimeForProject(
+    options: AgentProjectRuntimeProjectOptions,
+): Promise<AgentProjectRuntimeInfo | null> {
+    const runtimeRecord = findAgentProjectRuntimeRecord(options.agentPermanentId, options.projectName);
 
-    const runtimeIds = [...getAgentProjectRuntimeRegistryState().runtimesById.keys()];
+    if (!runtimeRecord) {
+        return null;
+    }
 
-    await Promise.all(runtimeIds.map((runtimeId) => terminateAgentProjectRuntimeById(runtimeId)));
+    return await removeAgentProjectRuntimeById(runtimeRecord.id);
 }
 
 /**
@@ -438,7 +493,7 @@ async function prepareAgentProjectRuntimeStart(
     options: AgentProjectRuntimeProjectOptions,
     project: NonNullable<Awaited<ReturnType<typeof resolveAgentProjectInfo>>>,
 ): Promise<PreparedAgentProjectRuntimeStart> {
-    await terminateAgentProjectRuntimeForProject({
+    await removeAgentProjectRuntimeForProject({
         agentPermanentId: options.agentPermanentId,
         projectName: project.projectName,
     });
@@ -595,12 +650,16 @@ function startChildProcessAgentProjectDevRuntime(runtimeRecord: MutableAgentProj
 }
 
 /**
- * Applies installer-managed nginx and SSL configuration when a public domain exists.
+ * Applies installer-managed nginx and SSL configuration when a project domain was added or changed.
+ *
+ * The generated nginx configuration resolves the runtime port of a project per request, so it only
+ * has to be regenerated when the set of project domains itself changes — never when an unchanged
+ * project is merely started again on a new port.
  */
 async function applyAgentProjectRuntimePublicConfiguration(
     domainAssignment: AgentProjectDomainAssignment,
 ): Promise<void> {
-    if (!domainAssignment.record) {
+    if (!domainAssignment.record || !domainAssignment.isChanged) {
         return;
     }
 
@@ -642,14 +701,8 @@ function findAgentProjectRuntimeRecord(
     agentPermanentId: string,
     projectName: string,
 ): MutableAgentProjectRuntimeRecord | null {
-    const normalizedAgentPermanentId = agentPermanentId.toLowerCase();
-    const normalizedProjectName = projectName.toLowerCase();
-
     for (const runtimeRecord of getAgentProjectRuntimeRegistryState().runtimesById.values()) {
-        if (
-            runtimeRecord.agentPermanentId.toLowerCase() === normalizedAgentPermanentId &&
-            runtimeRecord.projectName.toLowerCase() === normalizedProjectName
-        ) {
+        if (isSameAgentProjectIdentity(runtimeRecord, { agentPermanentId, projectName })) {
             return runtimeRecord;
         }
     }

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

@@ -0,0 +1,58 @@
+/**
+ * Global key used to keep one mutation queue per agent-project state file across module reloads.
+ */
+const AGENT_PROJECT_STATE_MUTATION_QUEUES_GLOBAL_KEY = '__PROMPTBOOK_AGENT_PROJECT_STATE_MUTATION_QUEUES__';
+
+/**
+ * Global object shape used for process-wide state-file mutation queues.
+ */
+type AgentProjectStateMutationQueuesGlobal = typeof globalThis & {
+    [AGENT_PROJECT_STATE_MUTATION_QUEUES_GLOBAL_KEY]?: Map<string, Promise<void>>;
+};
+
+/**
+ * Runs one agent-project state mutation after all previously queued mutations of the same state file finished.
+ *
+ * The project state files are read-modify-write JSON documents, so two concurrent mutations would
+ * silently drop one of the two changes. Every mutation of one file goes through its own queue, while
+ * mutations of unrelated files still run in parallel.
+ *
+ * @param queueName - Stable name of the mutated state file.
+ * @param operation - Mutation to run exclusively for that state file.
+ * @returns Whatever the mutation returns.
+ */
+export async function runAgentProjectStateMutation<TValue>(
+    queueName: string,
+    operation: () => Promise<TValue>,
+): Promise<TValue> {
+    const mutationQueues = getAgentProjectStateMutationQueues();
+    const previousMutation = mutationQueues.get(queueName) ?? Promise.resolve();
+    let releaseMutation!: () => void;
+
+    mutationQueues.set(
+        queueName,
+        new Promise<void>((resolve) => {
+            releaseMutation = resolve;
+        }),
+    );
+
+    await previousMutation.catch(() => undefined);
+
+    try {
+        return await operation();
+    } finally {
+        releaseMutation();
+    }
+}
+
+/**
+ * Returns the process-wide mutation queues of all agent-project state files.
+ *
+ * @returns Mutable map of pending mutations keyed by state file name.
+ */
+function getAgentProjectStateMutationQueues(): Map<string, Promise<void>> {
+    const mutationQueuesGlobal = globalThis as AgentProjectStateMutationQueuesGlobal;
+    mutationQueuesGlobal[AGENT_PROJECT_STATE_MUTATION_QUEUES_GLOBAL_KEY] ??= new Map();
+
+    return mutationQueuesGlobal[AGENT_PROJECT_STATE_MUTATION_QUEUES_GLOBAL_KEY]!;
+}

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

@@ -0,0 +1,48 @@
+import { readdir } from 'fs/promises';
+import { resolveLocalAgentRootPath } from '../localChatRunner/ensureLocalAgentFolder';
+import type { AgentProjectIdentity } from './agentProjectIdentity';
+import { parseAgentPermanentIdFromDirectoryName } from './agentProjectsPaths';
+import { isMissingPathError } from './isMissingPathError';
+import { listAgentProjectNames } from './listAgentProjectNames';
+
+/**
+ * Lists every project folder present on this machine, across all agents of all servers.
+ *
+ * Unlike `listAllAgentProjectSummaries` this never asks a database which agents exist and never
+ * measures a project tree — it only reads the two directory levels needed to name a project. That
+ * makes it usable before the first request is served, when no server database is selected yet.
+ *
+ * @returns Identities of all local agent projects ordered by agent and project name.
+ */
+export async function listAllLocalAgentProjectIdentities(): Promise<ReadonlyArray<AgentProjectIdentity>> {
+    const localAgentRootPath = resolveLocalAgentRootPath();
+    let localAgentRootEntries;
+
+    try {
+        localAgentRootEntries = await readdir(localAgentRootPath, { withFileTypes: true });
+    } catch (error) {
+        if (isMissingPathError(error)) {
+            return [];
+        }
+
+        throw error;
+    }
+
+    const agentPermanentIds = localAgentRootEntries
+        .filter((localAgentRootEntry) => localAgentRootEntry.isDirectory())
+        .map((agentDirectoryEntry) => parseAgentPermanentIdFromDirectoryName(agentDirectoryEntry.name))
+        .filter((agentPermanentId): agentPermanentId is string => agentPermanentId !== null)
+        .sort((firstAgentPermanentId, secondAgentPermanentId) =>
+            firstAgentPermanentId.localeCompare(secondAgentPermanentId),
+        );
+
+    const identitiesPerAgent = await Promise.all(
+        agentPermanentIds.map(async (agentPermanentId): Promise<ReadonlyArray<AgentProjectIdentity>> => {
+            const projectNames = await listAgentProjectNames(agentPermanentId);
+
+            return projectNames.map((projectName) => ({ agentPermanentId, projectName }));
+        }),
+    );
+
+    return identitiesPerAgent.flat();
+}

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

@@ -0,0 +1,23 @@
+/**
+ * Values accepted as an enabled on/off environment flag.
+ */
+const ENABLED_ENVIRONMENT_FLAG_VALUES = ['1', 'true', 'yes', 'y'];
+
+/**
+ * Reads one optional on/off environment flag used by the agent project runtime managers.
+ *
+ * An unset (or empty) variable is reported as `null` instead of `false`, so every caller keeps
+ * ownership of its own default while the accepted spellings of "enabled" stay defined in one place.
+ *
+ * @param environmentVariableName - Name of the environment variable to read.
+ * @returns `true` or `false` when the variable is set, `null` when it is not.
+ */
+export function resolveAgentProjectRuntimeEnvironmentFlag(environmentVariableName: string): boolean | null {
+    const configuredValue = process.env[environmentVariableName]?.trim().toLowerCase();
+
+    if (!configuredValue) {
+        return null;
+    }
+
+    return ENABLED_ENVIRONMENT_FLAG_VALUES.includes(configuredValue);
+}

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

@@ -0,0 +1,73 @@
+import { formatAgentProjectRuntimeStatus } from './agentProjectRuntimeDisplay';
+import { resolveAgentProjectRuntime } from './agentProjectRuntimeRegistry';
+import { resolveAgentProjectPublicUrls } from './resolveAgentProjectPublicUrls';
+
+/**
+ * Current runtime state of one project as shown on its project page.
+ */
+export type AgentProjectRuntimeStatusInfo = {
+    /**
+     * Whether the project currently accepts requests on its assigned runtime port.
+     */
+    readonly isRunning: boolean;
+
+    /**
+     * Human-readable status label, the same one the project page shows.
+     */
+    readonly statusLabel: string;
+
+    /**
+     * Stable public project URL, or `null` when the project has no assigned domain or runtime.
+     *
+     * The URL stays the same while the project is stopped, so a link to it keeps working once the
+     * project is started again.
+     */
+    readonly projectUrl: string | null;
+};
+
+/**
+ * Resolves the runtime state of one single project.
+ *
+ * This is the one-project counterpart of `listAgentProjectChatReferences`, for surfaces which
+ * already know which project they show and must not pay for listing every project of the agent.
+ *
+ * @param agentPermanentId - Permanent id of the agent owning the project.
+ * @param projectName - Project directory name.
+ * @returns Runtime state of the project.
+ */
+export async function resolveAgentProjectRuntimeStatus(
+    agentPermanentId: string,
+    projectName: string,
+): Promise<AgentProjectRuntimeStatusInfo> {
+    const runtime = await resolveAgentProjectRuntime(agentPermanentId, projectName);
+
+    return {
+        isRunning: runtime?.isRunning ?? false,
+        statusLabel: formatAgentProjectRuntimeStatus(runtime),
+        projectUrl: runtime?.publicUrl ?? (await resolveAssignedAgentProjectPublicUrl(agentPermanentId, projectName)),
+    };
+}
+
+/**
+ * Resolves the domain assigned to one project which currently has no runtime.
+ *
+ * The assignment is scoped by the domain the current server is reached under, which is known from
+ * the request headers only. A caller outside a request — such as the local chat runner finishing a
+ * message — therefore learns no URL instead of failing, and the project page link still works.
+ *
+ * @param agentPermanentId - Permanent id of the agent owning the project.
+ * @param projectName - Project directory name.
+ * @returns Assigned public project URL, or `null` when there is none to resolve.
+ *
+ * @private helper of `resolveAgentProjectRuntimeStatus`
+ */
+async function resolveAssignedAgentProjectPublicUrl(
+    agentPermanentId: string,
+    projectName: string,
+): Promise<string | null> {
+    try {
+        return (await resolveAgentProjectPublicUrls(agentPermanentId)).get(projectName.toLowerCase()) ?? null;
+    } catch {
+        return null;
+    }
+}

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

@@ -0,0 +1,110 @@
+import { createAgentProjectIdentityKey, type AgentProjectIdentity } from './agentProjectIdentity';
+import {
+    listAgentProjectRuntimeDesiredStates,
+    resolveAgentProjectRuntimeDesiredStateFromRecords,
+} from './agentProjectRuntimeDesiredState';
+import { listAgentProjectDomainRecords } from './agentProjectRuntimeDomains';
+import { resolveAgentProjectRuntime, startAgentProjectRuntime } from './agentProjectRuntimeRegistry';
+import { listAllLocalAgentProjectIdentities } from './listAllLocalAgentProjectIdentities';
+
+/**
+ * Outcome of one pass which brings all projects into their desired state.
+ */
+export type StartDefaultAgentProjectRuntimesReport = {
+    /**
+     * Number of projects started by this pass.
+     */
+    readonly startedProjectCount: number;
+
+    /**
+     * Number of projects which were already running or still coming up.
+     */
+    readonly runningProjectCount: number;
+
+    /**
+     * Number of projects left alone because they were explicitly stopped.
+     */
+    readonly stoppedProjectCount: number;
+
+    /**
+     * Number of projects which could not be started.
+     */
+    readonly failedProjectCount: number;
+};
+
+/**
+ * Starts every local project which is expected to be running but is not.
+ *
+ * This is what makes "running" the default state of a project: a project nobody explicitly stopped
+ * is started again after the server was restarted, after it crashed, and shortly after it was
+ * created. A project which somebody stopped stays stopped until it is started again.
+ *
+ * Projects are started one after another and one failing project never stops the pass, so a project
+ * with a broken dev command cannot keep every other project of the server down.
+ *
+ * @returns Summary of what the pass did.
+ */
+export async function startDefaultAgentProjectRuntimes(): Promise<StartDefaultAgentProjectRuntimesReport> {
+    const [projectIdentities, desiredStateRecords, projectDomainRecords] = await Promise.all([
+        listAllLocalAgentProjectIdentities(),
+        listAgentProjectRuntimeDesiredStates(),
+        listAgentProjectDomainRecords(),
+    ]);
+    const serverDomainByProjectKey = new Map(
+        projectDomainRecords.map((projectDomainRecord) => [
+            createAgentProjectIdentityKey(projectDomainRecord),
+            projectDomainRecord.serverDomain,
+        ]),
+    );
+
+    let startedProjectCount = 0;
+    let runningProjectCount = 0;
+    let stoppedProjectCount = 0;
+    let failedProjectCount = 0;
+
+    for (const projectIdentity of projectIdentities) {
+        if (resolveAgentProjectRuntimeDesiredStateFromRecords(desiredStateRecords, projectIdentity) === 'stopped') {
+            stoppedProjectCount++;
+            continue;
+        }
+
+        if (await isAgentProjectRuntimeAlreadyUp(projectIdentity)) {
+            runningProjectCount++;
+            continue;
+        }
+
+        try {
+            await startAgentProjectRuntime({
+                agentPermanentId: projectIdentity.agentPermanentId,
+                projectName: projectIdentity.projectName,
+                // Note: Keeps the project on the domain it was already assigned to, which is the only
+                //       way to tell servers of one VPS apart outside of a request.
+                serverDomain: serverDomainByProjectKey.get(createAgentProjectIdentityKey(projectIdentity)) ?? null,
+            });
+            startedProjectCount++;
+        } catch (error) {
+            failedProjectCount++;
+            console.error(
+                `[agent-project-runtimes] failed to start project \`${projectIdentity.projectName}\` of agent \`${projectIdentity.agentPermanentId}\``,
+                error,
+            );
+        }
+    }
+
+    return { startedProjectCount, runningProjectCount, stoppedProjectCount, failedProjectCount };
+}
+
+/**
+ * Returns whether one project already serves requests or is still coming up.
+ *
+ * A project which is still starting is left alone so that a slow dev command is not killed and
+ * restarted over and over by consecutive passes.
+ *
+ * @param projectIdentity - Agent and project identification.
+ * @returns `true` when the project must not be started again.
+ */
+async function isAgentProjectRuntimeAlreadyUp(projectIdentity: AgentProjectIdentity): Promise<boolean> {
+    const runtime = await resolveAgentProjectRuntime(projectIdentity.agentPermanentId, projectIdentity.projectName);
+
+    return Boolean(runtime && (runtime.isRunning || runtime.status === 'starting'));
+}

package/apps/agents-server/src/utils/agentReferenceResolver/MissingCoreAgentRecovery.ts

@@ -0,0 +1,19 @@
+/**
+ * Recovery offered for a missing agent reference that points to one of the bundled core agents.
+ *
+ * A core agent is never created from scratch like an ordinary missing reference — it is reinstated from the book
+ * bundled in the repository, together with every other core agent that happens to be missing at the same time.
+ *
+ * @private utility of Agents Server agent-reference diagnostics
+ */
+export type MissingCoreAgentRecovery = {
+    /**
+     * Titles of every bundled core agent currently missing on this server, including the referenced one.
+     */
+    readonly missingCoreAgentTitles: ReadonlyArray<string>;
+
+    /**
+     * Whether the current user is allowed to reinstate the missing core agents.
+     */
+    readonly isReinstateAllowed: boolean;
+};

package/apps/agents-server/src/utils/agentReferenceResolver/bookScopedAgentReferences.ts

@@ -2,6 +2,7 @@ import type { AgentReferenceResolver } from '../../../../../src/book-2.0/agent-s
 import { normalizeAgentName } from '../../../../../src/book-2.0/agent-source/normalizeAgentName';
 import { parseAgentSourceWithCommitments } from '../../../../../src/book-2.0/agent-source/parseAgentSourceWithCommitments';
 import { parseAgentSource } from '../../../../../src/book-2.0/agent-source/parseAgentSource';
+import { resolvePseudoAgentKindFromReference } from '../../../../../src/book-2.0/agent-source/pseudoAgentReferences';
 import type { string_book } from '../../../../../src/book-2.0/agent-source/string_book';
 import type { AgentCollection } from '../../../../../src/collection/agent-collection/AgentCollection';
 import type { BookCommitment } from '../../../../../src/commitments/_base/BookCommitment';
@@ -220,6 +221,12 @@ export function createBookScopedAgentReferenceResolver(options: {
                     chunks.push(content.slice(previousIndex, tokenMatch.index));
                     previousIndex = tokenMatch.index + tokenMatch.length;
 
+                    // Note: `Null`/`Void` (and other pseudo agents) are reserved language values, never embedded agents.
+                    if (resolvePseudoAgentKindFromReference(tokenReference)) {
+                        chunks.push(tokenMatch.token);
+                        continue;
+                    }
+
                     if (!tokenReference || !embeddedSources.has(normalizedTokenReference)) {
                         chunks.push(tokenMatch.token);
                         continue;