@promptbook/cli 0.114.0-2 → 0.114.0-21

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

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/agentProjectsPaths.ts

@@ -61,18 +61,28 @@ export function parseAgentPermanentIdFromDirectoryName(agentDirectoryName: strin
 }
 
 /**
- * Asserts that one path segment coming from a URL cannot escape its parent directory.
+ * Returns whether one path segment stays inside its parent directory.
  *
  * @param pathSegment - Single decoded path segment (project name or one file path part).
- * @param segmentPurpose - Human-readable description used in the error message.
- * @throws {NotAllowed} When the segment is empty or attempts path traversal.
+ * @returns `true` when the segment is non-empty and cannot escape its parent directory.
  */
-export function assertSafeAgentProjectPathSegment(pathSegment: string, segmentPurpose: string): void {
+export function isSafeAgentProjectPathSegment(pathSegment: string): boolean {
     const isTraversalSegment = pathSegment === '.' || pathSegment === '..';
     const hasPathSeparator = pathSegment.includes('/') || pathSegment.includes('\\');
     const hasNullByte = pathSegment.includes('\0');
 
-    if (pathSegment.length === 0 || isTraversalSegment || hasPathSeparator || hasNullByte) {
+    return pathSegment.length > 0 && !isTraversalSegment && !hasPathSeparator && !hasNullByte;
+}
+
+/**
+ * Asserts that one path segment coming from a URL cannot escape its parent directory.
+ *
+ * @param pathSegment - Single decoded path segment (project name or one file path part).
+ * @param segmentPurpose - Human-readable description used in the error message.
+ * @throws {NotAllowed} When the segment is empty or attempts path traversal.
+ */
+export function assertSafeAgentProjectPathSegment(pathSegment: string, segmentPurpose: string): void {
+    if (!isSafeAgentProjectPathSegment(pathSegment)) {
         throw new NotAllowed(
             spaceTrim(`
                 Invalid ${segmentPurpose} \`${pathSegment}\`.

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

@@ -0,0 +1,36 @@
+import { humanizeAgentProjectName } from './humanizeAgentProjectName';
+
+/**
+ * Maximum count of letters shown in one project initials icon.
+ */
+const AGENT_PROJECT_INITIALS_MAX_LENGTH = 3;
+
+/**
+ * Matches the first letter or digit of one word of a project name.
+ */
+const PROJECT_NAME_WORD_INITIAL_REGEX = /[\p{L}\p{N}]/u;
+
+/**
+ * Initials used for a project whose name has no letters and no digits at all.
+ */
+const AGENT_PROJECT_FALLBACK_INITIALS = '#';
+
+/**
+ * Creates the initials shown for one project which has no favicon.
+ *
+ * For example `prague-murders-map` becomes `PMM`.
+ *
+ * @param projectName - Project directory name.
+ * @returns Up to three uppercase initials of the project name.
+ */
+export function createAgentProjectInitials(projectName: string): string {
+    const projectInitials = humanizeAgentProjectName(projectName)
+        .split(/\s+/u)
+        .map((projectNameWord) => PROJECT_NAME_WORD_INITIAL_REGEX.exec(projectNameWord)?.[0] || '')
+        .filter((projectNameInitial) => projectNameInitial !== '')
+        .slice(0, AGENT_PROJECT_INITIALS_MAX_LENGTH)
+        .join('')
+        .toUpperCase();
+
+    return projectInitials || AGENT_PROJECT_FALLBACK_INITIALS;
+}

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

@@ -1,6 +1,22 @@
 import type { MarkdownInlineReference } from '@promptbook-local/types';
 import type { AgentProjectReferenceInfo } from './AgentProjectReferenceInfo';
-import { buildAgentProjectFilesHrefPrefix, buildAgentProjectProfileHref } from './agentProjectHrefs';
+import { buildAgentProjectFileHref, buildAgentProjectProfileHref } from './agentProjectHrefs';
+import { createAgentProjectInitials } from './createAgentProjectInitials';
+
+/**
+ * Stable action id used by a stopped project's open-and-start menu option.
+ */
+const OPEN_AGENT_PROJECT_ACTION_ID = 'open-agent-project';
+
+/**
+ * Stable action id used by a project runtime start menu option.
+ */
+const START_AGENT_PROJECT_ACTION_ID = 'start-agent-project';
+
+/**
+ * Stable action id used by a project runtime stop menu option.
+ */
+const STOP_AGENT_PROJECT_ACTION_ID = 'stop-agent-project';
 
 /**
  * Markdown inline reference data consumed by chat markdown rendering.
@@ -20,18 +36,40 @@ type CreateAgentProjectMarkdownReferencesOptions = {
      * Project references available to this agent chat.
      */
     readonly projects: ReadonlyArray<AgentProjectMarkdownReferenceInfo>;
+
+    /**
+     * Opens a project, starting its runtime first when needed.
+     */
+    readonly onOpenProject?: (project: AgentProjectMarkdownReferenceInfo) => void | Promise<void>;
+
+    /**
+     * Starts or stops one project runtime.
+     */
+    readonly onChangeProjectRuntime?: (
+        project: AgentProjectMarkdownReferenceInfo,
+        isRunning: boolean,
+    ) => void | Promise<void>;
 };
 
 /**
  * Project fields required to create a chat markdown reference.
  */
-type AgentProjectMarkdownReferenceInfo = Pick<
+export type AgentProjectMarkdownReferenceInfo = Pick<
     AgentProjectReferenceInfo,
-    'projectName' | 'displayName' | 'description' | 'isRunning' | 'projectUrl'
+    'projectName' | 'displayName' | 'description' | 'faviconRelativePath' | 'isRunning' | 'projectUrl'
 >;
 
 /**
- * Creates markdown references that render known `[[project-name]]` tokens as project profile chips.
+ * One menu option belonging to a project markdown reference.
+ */
+type AgentProjectMarkdownReferenceMenuOption = NonNullable<AgentProjectMarkdownReference['menu']>['options'][number];
+
+/**
+ * Creates markdown references rendering every mention of one project as a project chip.
+ *
+ * One project is mentioned either by its display name in chat prose, its `[[project-name]]` token,
+ * a link into its project page or files, or its public project URL. All of them render the same chip
+ * showing the project name together with its running state.
  *
  * @param options - Agent and project metadata.
  * @returns Inline markdown references for the shared chat renderer.
@@ -42,38 +80,105 @@ export function createAgentProjectMarkdownReferences(
     return options.projects.map((project) => {
         const projectProfileHref = buildAgentProjectProfileHref(options.agentPermanentId, project.projectName);
         const projectUrl = project.projectUrl || null;
+        const label = project.displayName || project.projectName;
+        const faviconHref = project.faviconRelativePath
+            ? buildAgentProjectFileHref(options.agentPermanentId, project.projectName, project.faviconRelativePath)
+            : null;
 
         return {
             reference: project.projectName,
-            label: project.displayName || project.projectName,
+            sourceTextAliases: [label],
+            label,
             href: projectProfileHref,
-            sourceHrefPrefixes: [
-                projectProfileHref,
-                buildAgentProjectFilesHrefPrefix(options.agentPermanentId, project.projectName),
-                ...(projectUrl ? [projectUrl] : []),
-            ],
-            title: project.description || project.displayName || project.projectName,
+            sourceHrefPrefixes: [projectProfileHref, ...(projectUrl ? [projectUrl] : [])],
+            title: project.description || label,
+            icon: {
+                src: faviconHref,
+                fallbackText: createAgentProjectInitials(project.projectName),
+            },
             menu: {
                 status: {
                     label: project.isRunning ? 'Project is running' : 'Project is not running',
                     isActive: project.isRunning ?? false,
                 },
                 options: [
-                    {
-                        label: 'Open the project in a new tab',
-                        href: project.isRunning ? projectUrl : null,
-                        title:
-                            project.isRunning && projectUrl
-                                ? 'Open the project in a new tab'
-                                : 'The project must run before it can be opened.',
-                    },
+                    createOpenAgentProjectMenuOption(project, options.onOpenProject),
                     {
                         label: 'Open the project page in a new tab',
                         href: projectProfileHref,
                         title: 'Open the project page in a new tab',
                     },
+                    ...(options.onChangeProjectRuntime
+                        ? [createChangeAgentProjectRuntimeMenuOption(project, options.onChangeProjectRuntime)]
+                        : []),
                 ],
             },
         };
     });
 }
+
+/**
+ * Creates the project destination option, using a client action when the runtime must be started.
+ *
+ * @param project - Project represented by the menu.
+ * @param onOpenProject - Optional open-and-start callback.
+ * @returns Project destination menu option.
+ */
+function createOpenAgentProjectMenuOption(
+    project: AgentProjectMarkdownReferenceInfo,
+    onOpenProject: CreateAgentProjectMarkdownReferencesOptions['onOpenProject'],
+): AgentProjectMarkdownReferenceMenuOption {
+    const projectUrl = project.projectUrl || null;
+
+    if (project.isRunning && projectUrl) {
+        return {
+            label: 'Open the project in a new tab',
+            href: projectUrl,
+            title: 'Open the project in a new tab',
+        };
+    }
+
+    if (onOpenProject) {
+        return {
+            label: 'Open the project in a new tab',
+            href: null,
+            title: 'Start the project and open it in a new tab',
+            action: {
+                id: OPEN_AGENT_PROJECT_ACTION_ID,
+                onSelect: () => onOpenProject(project),
+            },
+        };
+    }
+
+    return {
+        label: 'Open the project in a new tab',
+        href: null,
+        title: 'The project must run before it can be opened.',
+    };
+}
+
+/**
+ * Creates the start or stop action matching a project's current runtime state.
+ *
+ * @param project - Project represented by the menu.
+ * @param onChangeProjectRuntime - Runtime state callback.
+ * @returns Start or stop project menu option.
+ */
+function createChangeAgentProjectRuntimeMenuOption(
+    project: AgentProjectMarkdownReferenceInfo,
+    onChangeProjectRuntime: NonNullable<CreateAgentProjectMarkdownReferencesOptions['onChangeProjectRuntime']>,
+): AgentProjectMarkdownReferenceMenuOption {
+    const isRunning = project.isRunning === true;
+    const actionId = isRunning ? STOP_AGENT_PROJECT_ACTION_ID : START_AGENT_PROJECT_ACTION_ID;
+    const label = isRunning ? 'Stop the project' : 'Start the project';
+
+    return {
+        label,
+        href: null,
+        title: label,
+        action: {
+            id: actionId,
+            onSelect: () => onChangeProjectRuntime(project, !isRunning),
+        },
+    };
+}