@promptbook/cli 0.114.0-2 → 0.114.0-21

package/apps/agents-server/src/utils/agentGoalChat.ts

@@ -0,0 +1,25 @@
+export { AGENT_GOAL_CHAT_TITLE } from './agentGoalChat/agentGoalChatConstants';
+export {
+    AGENT_GOAL_CHAT_ID_PREFIX,
+    buildAgentGoalChatId,
+    isAgentGoalChatId,
+} from './agentGoalChat/agentGoalChatIdentity';
+export { appendAgentGoalChatNote } from './agentGoalChat/appendAgentGoalChatNote';
+export { canAccessAgentGoalChat } from './agentGoalChat/canAccessAgentGoalChat';
+export {
+    createAgentGoalChatCancelledPlannedMessageNoteContent,
+    createAgentGoalChatLifecycleNoteContent,
+    createAgentGoalChatPlannedMessageNoteContent,
+    createAgentGoalChatUpdatedPlannedMessageNoteContent,
+} from './agentGoalChat/createAgentGoalChatNoteContent';
+export { ensureAgentGoalChat } from './agentGoalChat/ensureAgentGoalChat';
+export {
+    createAgentGoalChatLifecycleClientMessageId,
+    enqueueAgentGoalChatTurn,
+} from './agentGoalChat/enqueueAgentGoalChatTurn';
+export { prependAgentGoalChatSummarySeed } from './agentGoalChat/prependAgentGoalChatSummarySeed';
+export { recordAgentGoalChatLifecycleNote } from './agentGoalChat/recordAgentGoalChatLifecycleNote';
+export { resolveEffectiveAgentGoal } from './agentGoalChat/resolveEffectiveAgentGoal';
+export { resolveAgentGoalChatOwnerUserId } from './agentGoalChat/resolveAgentGoalChatOwnerUserId';
+export { scheduleAgentGoalChatModifiedNote } from './agentGoalChat/scheduleAgentGoalChatModifiedNote';
+export type { AgentGoalChatLifecycleEvent } from './agentGoalChat/createAgentGoalChatNoteContent';

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

@@ -12,7 +12,8 @@ export type AgentProjectInfo = {
     readonly projectName: string;
 
     /**
-     * User-facing name of the project, resolved from the README heading when available.
+     * User-facing name of the project, resolved from the README heading, the `index.html` title
+     * or the humanized project directory name.
      */
     readonly displayName: string;
 
@@ -26,6 +27,14 @@ export type AgentProjectInfo = {
      */
     readonly readmeFileName: string | null;
 
+    /**
+     * Path of the project icon relative to the project root, or `null` when the project has no icon.
+     *
+     * The icon is the favicon linked by the project `index.html` or a favicon found in one of the
+     * conventional locations; a project without one is shown with an icon made of its initials.
+     */
+    readonly faviconRelativePath: string | null;
+
     /**
      * Path of the project relative to the agent folder root, for example `projects/my-website`.
      */

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

@@ -5,7 +5,7 @@ import type { AgentProjectInfo } from './AgentProjectInfo';
  */
 export type AgentProjectReferenceInfo = Pick<
     AgentProjectInfo,
-    'projectName' | 'displayName' | 'description' | 'sizeBytes'
+    'projectName' | 'displayName' | 'description' | 'sizeBytes' | 'faviconRelativePath'
 > & {
     /**
      * Whether the project currently accepts requests on its assigned runtime port.
@@ -13,7 +13,10 @@ export type AgentProjectReferenceInfo = Pick<
     readonly isRunning?: boolean;
 
     /**
-     * Public runtime URL when the project has been assigned a runtime, otherwise `null`.
+     * Stable public project URL when the project has an assigned runtime or domain, otherwise `null`.
+     *
+     * The URL stays the same while the project is stopped so that the project stays recognizable
+     * wherever it is referenced.
      */
     readonly projectUrl?: string | null;
 };

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

@@ -0,0 +1,14 @@
+/**
+ * Browser-safe runtime state returned after a project chip action.
+ */
+export type AgentProjectRuntimeActionResult = {
+    /**
+     * Whether the project accepts requests after the action completes.
+     */
+    readonly isRunning: boolean;
+
+    /**
+     * Public project URL assigned to the runtime, or `null` when none is available.
+     */
+    readonly projectUrl: string | null;
+};

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

@@ -0,0 +1,21 @@
+/**
+ * HTML entrypoint filenames recognized at the root of one agent project, ordered by priority.
+ *
+ * The static project server serves the first existing one of them for a directory request, so the
+ * same list decides which file describes the project — its `<title>` and its favicon.
+ */
+export const AGENT_PROJECT_INDEX_HTML_FILE_NAMES = ['index.html', 'index.htm'] as const;
+
+/**
+ * Conventional favicon locations searched inside one agent project, ordered by priority.
+ *
+ * They are used only when the project `index.html` does not link its icon explicitly.
+ */
+export const AGENT_PROJECT_CONVENTIONAL_FAVICON_RELATIVE_PATHS = [
+    'favicon.ico',
+    'favicon.svg',
+    'favicon.png',
+    'public/favicon.ico',
+    'public/favicon.svg',
+    'public/favicon.png',
+] as const;

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

@@ -43,17 +43,6 @@ export function buildAgentProjectProfileHref(agentPermanentId: string, projectNa
     return `${buildAgentProjectsDashboardHref(agentPermanentId)}/${encodeURIComponent(projectName)}`;
 }
 
-/**
- * Builds the href prefix serving files from one agent project.
- *
- * @param agentPermanentId - Permanent id of the agent.
- * @param projectName - Project directory name.
- * @returns Project file href prefix.
- */
-export function buildAgentProjectFilesHrefPrefix(agentPermanentId: string, projectName: string): string {
-    return `${buildAgentProjectProfileHref(agentPermanentId, projectName)}/files/`;
-}
-
 /**
  * Builds the href of one project on its owning server.
  *
@@ -118,6 +107,26 @@ export function buildAgentProjectFileHref(
     return `${buildAgentProjectProfileHref(agentPermanentId, projectName)}/files/${encodedFilePath}`;
 }
 
+/**
+ * Builds the href serving one raw file of one agent project on its owning server.
+ *
+ * @param options - Project file and server identity.
+ * @returns Server-scoped raw project file href.
+ */
+export function buildAgentProjectFileHrefForServer(options: {
+    readonly agentPermanentId: string;
+    readonly projectName: string;
+    readonly fileRelativePath: string;
+    readonly serverDomain: string | null;
+    readonly currentServerDomain: string | null;
+}): string {
+    return buildAgentProjectHrefForServer(
+        buildAgentProjectFileHref(options.agentPermanentId, options.projectName, options.fileRelativePath),
+        options.serverDomain,
+        options.currentServerDomain,
+    );
+}
+
 /**
  * Builds the href opening one project in browser VS Code.
  *

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

@@ -0,0 +1,46 @@
+import { isSameAgentPermanentId } from '../agentIdentifier';
+
+/**
+ * Identity of one agent project, shared by every project runtime state store.
+ */
+export type AgentProjectIdentity = {
+    /**
+     * Permanent id of the agent owning the project.
+     */
+    readonly agentPermanentId: string;
+
+    /**
+     * Directory name of the project inside the agent `projects/` folder.
+     */
+    readonly projectName: string;
+};
+
+/**
+ * Creates the case-insensitive lookup key of one agent project.
+ *
+ * Agent permanent ids and project directory names are compared without letter casing everywhere,
+ * so state stores keyed by this function can never hold two entries for the same project.
+ *
+ * @param identity - Agent and project identification.
+ * @returns Lookup key usable in a `Map` or `Set`.
+ */
+export function createAgentProjectIdentityKey(identity: AgentProjectIdentity): string {
+    return `${identity.agentPermanentId.toLowerCase()}/${identity.projectName.toLowerCase()}`;
+}
+
+/**
+ * Returns whether two identities describe the same agent project.
+ *
+ * @param firstIdentity - First agent and project identification.
+ * @param secondIdentity - Second agent and project identification.
+ * @returns `true` when both identities point at the same project of the same agent.
+ */
+export function isSameAgentProjectIdentity(
+    firstIdentity: AgentProjectIdentity,
+    secondIdentity: AgentProjectIdentity,
+): boolean {
+    return (
+        isSameAgentPermanentId(firstIdentity.agentPermanentId, secondIdentity.agentPermanentId) &&
+        firstIdentity.projectName.toLowerCase() === secondIdentity.projectName.toLowerCase()
+    );
+}

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';
 }
-